<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <title>[1.32]-在线接口文档：注释规范 | PhalApi(π框架) - PHP轻量级开源接口框架 - 助你创造价值！</title>
    <meta name="viewport" content="width=device-width,initial-scale=1,minimum-scale=1,maximum-scale=1,user-scalable=no" />
    <meta content="yes" name="apple-mobile-web-app-capable">
    <meta content="black" name="apple-mobile-web-app-status-bar-style">
    <meta content="telephone=no" name="format-detection">
    <meta content="email=no" name="format-detection">
    <meta name="Author" content="PhalApi,ecitlm,dogstar">
    <meta name="description" content="[1.32]-在线接口文档：注释规范，PhalApi是一个PHP轻量级开源接口框架，致力于快速开发接口服务。支持HTTP/SOAP/RPC等协议，可用于搭建接口/微服务/RESTful接口/Web Services。我们不断更新，保持生气；为接口负责，为开源负责！并承诺永久免费！">
    <meta name="keywords" content="PhalApi,phalapi,phalapi接口开发,后台接口开发,后台接口开发框架,接口开发,接口框架,开源接口框架,PHP后台接口开发,PHP接口开发,PHP接口框架,PHP后台接口框架,phalapi官网,PHP接口框架,php接口开发框架,php接口开发,php web框架,π框架,π开发框架,π接口框架,π接口开发框架,api接口,php接口,,PHP接口框架,phalapi文档,phalapi wiki,PhalApi文档,phalapi在线文档,phalapi官方文档">

    <link rel="stylesheet" type="text/css" href="https://cdn.bootcss.com/bootstrap/3.3.7/css/bootstrap.min.css" media="screen">
    <link rel="stylesheet" type="text/css" href="https://cdn.bootcss.com/font-awesome/4.7.0/css/font-awesome.css" media="screen">
    <link rel="stylesheet" href="../css/main.css" />
    <link rel="stylesheet" href="../css/loading_bar.css" />
    <link rel="icon" href="http://webtools.qiniudn.com/dog_catch.png" type="image/x-icon" />
    <script src="../js/pace.min.js"></script>
	
	<!-- 代码高亮 -->
	<link rel="stylesheet" href="../css/highlight.min.css">
	<script src="../js/highlight.min.js"></script>
	<script>hljs.initHighlightingOnLoad();</script>
    
</head>

<body>
    <!-- navbar start -->
    <div class="navbar navbar-default navbar-fixed-top" id="mainnav" role="navigation">
        <div class="container">
            <div class="navbar-header">
                <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target=".navbar-collapse">
                    <span class="sr-only">Toggle navigation</span>
                    <span class="icon-bar"></span>
                    <span class="icon-bar"></span>
                    <span class="icon-bar"></span>
                </button>
                <a class="navbar-brand website_name" href="/"><!-- <span>PhalApi</span> --><strong>PhalApi</strong></a>
            </div>
            <div class="navbar-collapse collapse" aria-expanded="false" style="height: 1px;">
                <ul class="nav navbar-nav navbar-right" id="nav_bar">
                    <li><a href="/"><span class="glyphicon glyphicon-home"></span></a></li>
                    <li><a href="http://qa.phalapi.net/">社区</a></li>
                    <li><a href="/download.html">下载</a></li>
                    <li class="active"><a href="/wikis/">文档</a></li>
                    <li><a href="http://www.ituring.com.cn/book/2405">书籍</a></li>
                    <li><a href="http://demo.phalapi.net/">体验</a></li>
                    <li><a href="/about.html">关于</a></li>
                    <li><a href="/donate.html">贡献</a></li>
                    <li><a href="/wikis/en/">English</a></li>
                </ul>
            </div>
            <!--/.nav-collapse -->
        </div>
    </div>
    <!-- navbar end -->


    <div id="content">
        <div class="container">
            <div class="row row-md-flex row-md-flex-wrap">
                <h4><a href="/wikis/%5B1.31%5D-%E6%96%B0%E5%9E%8B%E8%AE%A1%E5%88%92%E4%BB%BB%E5%8A%A1%EF%BC%9A%E4%BB%A5%E6%8E%A5%E5%8F%A3%E5%BD%A2%E5%BC%8F%E5%AE%9E%E7%8E%B0%E7%9A%84%E8%AE%A1%E5%88%92%E4%BB%BB%E5%8A%A1.html">上一章</a>   <a href="/wikis/">文档首页</a>   <a href="/wikis/[1.33]-开发者工具：实用函数.html">下一章</a></h4>
<hr />
<h2>1.32.1 在线接口文档</h2>
<p>在线接口文档，主要有两种：  </p>
<ul>
<li>接口列表：用于罗列全部的接口；</li>
<li>接口文档：针对单个接口的文档，用于显示该接口服务的基本信息、接口说明、接口参数、返回结果以及异常情况等。</li>
</ul>
<p>下面分别进行解释。  </p>
<h2>1.32.2 接口列表</h2>
<h3>如何访问接口列表？</h3>
<p>在<a href="/wikis/%5B1.2%5D-%E5%88%9B%E5%BB%BA%E4%B8%80%E4%B8%AA%E8%87%AA%E5%B7%B1%E7%9A%84%E9%A1%B9%E7%9B%AE.html">创建一个自己的项目</a>后，可以通过访问对应项目下的<code>listAllApis.php</code>文件来访问接口列表。<br />
具体的URL路径，根据项目的部署情况而定，通常是：  </p>
<pre><code>#域名 + 路径 + 项目名 + listAllApis.php
http://localhost/Public/demo/listAllApis.php</code></pre>
<p>如访问：<a href="http://demo.phalapi.net/listAllApis.php"><a href="http://demo.phalapi.net/listAllApis.php">http://demo.phalapi.net/listAllApis.php</a></a>，效果如下：<br />
<img src="http://7xiz2f.com1.z0.glb.clouddn.com/20170205154748.png" alt="" />  </p>
<h3>接口列表的注释规范</h3>
<p>接口列表的注释比较简单，其规范如下：  </p>
<ul>
<li>序号：自动生成，按接口服务名称字典排序后从小到大依次编号</li>
<li>接口服务：自动生成，即service英文接口服务名称</li>
<li>接口名称：接口中文名称，不带任何注解的注释，通常为第一行注释</li>
<li>更多说明：对应@desc 注释，注释内容中不能带有空格</li>
</ul>
<p>与上面接口列表对应的注释，以<code>User.GetBaseInfo</code>为例，其注释为：  </p>
<pre><code class="language-php">class Api_User extends PhalApi_Api {

    /**
     * 获取用户基本信息
     * @desc 用于获取单个用户基本信息
     */
    public function getBaseInfo() {
    }
}</code></pre>
<p>结合以上示例，可以看出：  </p>
<ul>
<li>接口服务：由类名Api_User和方法名getBaseInfo组合而成，即：User.GetBaseInfo</li>
<li>接口名称：即：获取用户基本信息</li>
<li>更多说明：对应@desc 注释，即：用于获取单个用户基本信息</li>
</ul>
<h2>1.32.3 接口文档</h2>
<h3>如何访问接口文档？</h3>
<p>在进入接口列表后，点击对应的接口服务即可跳转到对应的接口文档。或者，也可以手动拼接访问。其URL路径与<code>listAllApis.php</code>类似，但需要访问的是<code>checkApiParams.php</code>，通常是：  </p>
<pre><code>#域名 + 路径 + 项目名 + checkApiParams.php?service=接口服务
http://localhost/Public/demo/checkApiParams.php?service=User.GetBaseInfo</code></pre>
<p>如访问：<a href="http://demo.phalapi.net/checkApiParams.php?service=User.GetBaseInfo"><a href="http://demo.phalapi.net/checkApiParams.php?service=User.GetBaseInfo">http://demo.phalapi.net/checkApiParams.php?service=User.GetBaseInfo</a></a>，效果如下：
<img src="http://7xiz2f.com1.z0.glb.clouddn.com/20170205155942.jpg" alt="" /><br />
<img src="http://7xiz2f.com1.z0.glb.clouddn.com/20170205160005.png" alt="" />  </p>
<h3>接口文档的注释规范</h3>
<p>接口文档的注释较多，开发人员可在进行项目开发时按需注释。但各部分也很简单明了，如下：  </p>
<ul>
<li>接口服务与接口名称：分别对应上面接口列表中接口服务英文名称和的接口中文名称   </li>
<li>接口说明：对应@desc 注释，注释内容中不能带有空格</li>
<li>接口参数：由<code>PhalApi_Api::getRules()</code>中具体接口类定义的接口参数自动生成</li>
<li>返回结果：对应@return 注释，可以有多组，格式为：@return 返回类型 返回字段 说明（不带空格）</li>
<li>异常情况：对应@exception 注释，可以有多组，格式为：@exception 错误码 错误描述信息</li>
</ul>
<blockquote>
<p>温馨提示：@exception 注释需要PhalApi 1.3.6及以上版本</p>
</blockquote>
<p>上面示例中，<code>User.GetBaseInfo</code>接口文档对应的注释为：  </p>
<pre><code class="language-php">class Api_User extends PhalApi_Api {

    public function getRules() {
        return array(
            'getMultiBaseInfo' =&gt; array(
                'userIds' =&gt; array('name' =&gt; 'user_ids', 'type' =&gt; 'array', 'format' =&gt; 'explode', 'require' =&gt; true, 'desc' =&gt; '用户ID，多个以逗号分割'),
            ),
        );
    }

    /**
     * 批量获取用户基本信息
     * @desc 用于获取多个用户基本信息
     * @return int code 操作码，0表示成功
     * @return array list 用户列表
     * @return int list[].id 用户ID
     * @return string list[].name 用户名字
     * @return string list[].note 用户来源
     * @return string msg 提示信息
     * @exception 400 参数传递错误
     * @exception 500 服务器内部错误
     */
    public function getMultiBaseInfo() {
    }
}</code></pre>
<p>其中，  </p>
<ul>
<li>接口服务与接口名称：由Api_User类名和getMultiBaseInfo方法名生成英文名称，中文名称为不带任何注解的注释：批量获取用户基本信息</li>
<li>接口说明：对应@desc 注释，即：用于获取多个用户基本信息</li>
<li>接口参数：由<code>Api_User::getRules()</code>中定义的接口参数自动生成</li>
<li>返回结果：对应@return 注释，共有6组</li>
<li>异常情况：对应@exception 注释，共有2组</li>
</ul>
<h3>公共的<code>@exception</code>和<code>@return</code>注释</h3>
<p>对于当前类函数成员公共的<code>@exception</code>异常情况注释和<code>@return</code>返回结果注释，可在类注释中统一放置。而对于多个类公共的@exception<code>和</code>@return```注释，则可以在父类的类注释中统一放置。</p>
<p>例如，对于上面的Api_User类，可以添加全部函数成员都适用的注释。例如，Api_User类的全部接口都返回code字段，且都返回400和500异常，则可以：  </p>
<pre><code class="language-php">&lt;?php
/**
 * @return int code 操作码，0表示成功
 * @exception 400 参数传递错误
 * @exception 500 服务器内部错误
 */
class Api_User extends PhalApi_Api {</code></pre>
<p>这样就不需要在每个函数成员的注释中重复注释。此外，也会依次解析父类中的相关注释。对于相同异常码的<code>@exception</code>注释，子类的注释会覆盖父类的注释，方法的注释会覆盖类的注释；而对于相同的返回结果<code>@return</code>注释，也一样。  </p>
<blockquote>
<p>温馨提示：公共的<code>@exception</code>和<code>@return</code>注释需要PhalApi 1.4.0及以上版本</p>
</blockquote>
<h2>1.32.4 生成离线文档</h2>
<p>除了使用访问在线文档，也可以生成熟线文档。在命令行，通过CLI方式访问上面的listAllApis.php文件即可生成离线文档到相应的项目目录下。  </p>
<p>以Demo项目为例，先执行listAllApis.php脚本生成离线文档。  </p>
<pre><code class="language-bash">$ php /path/to/Public/demo/listAllApis.php</code></pre>
<p>生成完毕后，可以看到类似这样的输出：  </p>
<pre><code>脚本执行完毕！离线文档保存路径为：/path/to/PhalApi/Public/demo/doc</code></pre>
<p>随后，在浏览器打开并访问：  </p>
<pre><code>http://localhost/PhalApi/Public/demo/doc/index.html</code></pre>
<p>便可看到生成好的离线文档了。  </p>
<p>自 PhalApi 1.4.1 版本开始，在线接口列表文档有两种主题风格，分别是折叠版和展开版。折叠版是指带有左侧分类菜单的方式，展开版则是一次性罗列全部接口服务，便于搜索。在生成离线文档时，可以通过第二个参数，指定主题风格。如：  </p>
<ul>
<li>
<p>生成展开版</p>
<pre><code class="language-bash">$ php /path/to/Public/demo/listAllApis.php expand</code></pre>
</li>
<li>生成折叠版
<pre><code class="language-bash">$ php /path/to/Public/demo/listAllApis.php fold</code></pre></li>
</ul>
<blockquote>
<p>温馨提示：生成离线功能需要 PhalApi 1.4.1 及以上版本支持。  </p>
</blockquote>
<hr />
<h4><a href="/wikis/%5B1.31%5D-%E6%96%B0%E5%9E%8B%E8%AE%A1%E5%88%92%E4%BB%BB%E5%8A%A1%EF%BC%9A%E4%BB%A5%E6%8E%A5%E5%8F%A3%E5%BD%A2%E5%BC%8F%E5%AE%9E%E7%8E%B0%E7%9A%84%E8%AE%A1%E5%88%92%E4%BB%BB%E5%8A%A1.html">上一章</a>   <a href="/wikis/">文档首页</a>   <a href="/wikis/[1.33]-开发者工具：实用函数.html">下一章</a></h4><div style="float: left">
<h4>
<a href="http://qa.phalapi.net/">还有疑问？欢迎到社区提问！</a>
</h4>
</div>
            </div>
        </div>
    </div>

 <!-- 广告位 -->
<div class="grid-wrapper desktop-only">
	<p align="center">
		<a href="http://7xiz2f.com1.z0.glb.clouddn.com/%E6%88%91%E7%9A%84%E5%90%8D%E5%AD%97%E5%8F%AB%EF%BC%9A%CF%80%E6%A1%86%E6%9E%B6%20-%20PhalApi%202016%E5%B9%B4%E5%BA%A6%E5%BC%80%E6%BA%90%E6%80%BB%E7%BB%93%20-%20%E5%AE%98%E6%96%B9%E5%87%BA%E5%93%81.pdf" target="blank"><img width="950" height="100" src="http://7xiz2f.com1.z0.glb.clouddn.com/ad_20170104.png"></a>
		<a href="http://www.itran.cc/" target="blank"><img width="950" height="100" src="http://7xslqv.com1.z0.glb.clouddn.com/images/9/69/b88bc92455dc1239f9a5bf8d72929.png"></a>
		<a href="http://web-tools.phalapi.net/" target="blank"><img width="950" height="100" src="http://7xslqv.com1.z0.glb.clouddn.com/images/7/d0/88f523566c482296aecc43d185ca2.png"></a>
	</p>
</div>

        <!-- footer -->
        <div class="footer">
            <div class="link container ">
                <div class=" col-xs-7 col-sm-7 col-md-7 col-lg-7 ">
                    <h3>PhalApi (π框架)</h3>
                    <p>一个轻量级PHP开源接口框架，专注于接口服务开发，支持HTTP/SOAP/RPC协议，拥有自动生成的在线文档、多种开发语言的客户端SDK包以及可重用的扩展类库，可用于快速搭建微服务、RESTful接口或Web
                        Services。</p>
                    <!-- <p>:</p> -->
                    <span>友情链接:</span>
                    <a href="https://www.phalapi.net/" target="_blank"> PhalApi </a>
                    <a href="http://www.oschina.net/" target="_blank"> 开源中国 </a>
                    <a href="https://www.itran.cc/" target="_blank">艾翻译</a>
                    <a href="http://www.phalconphp.com/en/" target="_blank">Phalcon</a>
                    <a href="https://phpunit.de/manual/3.7/zh_cn/automating-tests.html" target="_blank">PHPUnit</a>
                    <a href="http://www.thoughtworks.com/cn/" target="_blank">ThoughtWorks</a>
                    <a href="mailto:chanzonghuang@gmail.com">友链交换</a>

                </div>
                <div class=" col-xs-5 col-sm-5 col-md-5 col-lg-5 contact_us ">
                    <h3>联系我们</h3>
                    <a href="https://github.com/phalapi/phalapi"><img src="../images/github.png" alt="github" /></a>
                    <a href="http://weibo.com/p/100808d236e99beb645bfb56ed1c37dde9b8bd?k=phalapi%E5%BC%80%E6%BA%90%E6%A1%86%E6%9E%B6&from=501&_from_=huati_topic"><img src="../images/weibo.png"  alt="weibo" /></a>
                    <a href="http://7xslqv.com1.z0.glb.clouddn.com/images/1/b0/894fde762850cb11250253f7d5ede.png"><img src="../images/zfb.png"  alt="zfb" /></a>
                    <a href="https://jq.qq.com/?_wv=1027&k=4A6reum"><img src="../images/qq.png"  alt="qq" /></a>
					<a href="http://git.oschina.net/dogstar/PhalApi"><img src="../images/git-oschina.png"  alt="git-oschina" /></a>
                </div>
                <div class="cls"></div>
                <div class="text-center copy_right"> ©2015-2017 PhalApi All Rights Reserved. <a href="http://www.miitbeian.gov.cn" target="_blank">粤ICP备15028808号</a>

				<script type="text/javascript">var cnzz_protocol = (("https:" == document.location.protocol) ? " https://" : " http://");document.write(unescape("%3Cspan id='cnzz_stat_icon_1255326144'%3E%3C/span%3E%3Cscript src='" + cnzz_protocol + "s4.cnzz.com/z_stat.php%3Fid%3D1255326144%26show%3Dpic' type='text/javascript'%3E%3C/script%3E"));</script>
                </div>
            </div>
        </div>
    </div>


    <a href="https://github.com/phalapi"><img id="gitHub_fllow" style="position: fixed; top: 0; right: 0; border: 0;z-index:9999" src="https://camo.githubusercontent.com/652c5b9acfaddf3a9c326fa6bde407b87f7be0f4/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f6f72616e67655f6666373630302e706e67" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png"></a>


    <script src="../js/jquery-1.11.1.min.js"></script>
    <script src="../js/bootstrap.min.js"></script>
</body>

</html>